
/*
 * Copyright (C) Igor Sysoev
 * Copyright (C) Nginx, Inc.
 */


#include <ngx_config.h>
#include <ngx_core.h>

#if (NGX_HAVE_ATOMIC_OPS)//当 NGX_HAVE_ATOMIC_OPS 宏被定义时，表示当前平台支持原子操作

// 唤醒等待共享内存锁的进程
static void ngx_shmtx_wakeup(ngx_shmtx_t *mtx);

#endif
// 创建共享内存锁
ngx_int_t//ngx_shmtx_create 函数用于创建共享内存锁，它接收三个参数，分别是共享内存锁对象、共享内存锁的地址和共享内存锁的名字
ngx_shmtx_create(ngx_shmtx_t *mtx, ngx_shmtx_sh_t *addr, u_char *name)//addr是共享内存的地址
{
    // 设置锁的地址
    mtx->lock = &addr->lock;

    // 如果 spin 的值为 -1，则直接返回
    if (mtx->spin == (ngx_uint_t) -1) {
        return NGX_OK;
    }

    // 设置 spin 的值为 2048
    mtx->spin = 2048;

#if (NGX_HAVE_POSIX_SEM)//如果支持 POSIX 信号量
    // 如果支持 POSIX 信号量，则初始化信号量
    mtx->wait = &addr->wait;

    // 初始化信号量，如果失败则记录错误日志，否则设置 semaphore 标志位
    if (sem_init(&mtx->sem, 1, 0) == -1) {
        ngx_log_error(NGX_LOG_ALERT, ngx_cycle->log, ngx_errno,
                      "sem_init() failed");
    } else {
        mtx->semaphore = 1;
    }

#endif

    // 返回成功
    return NGX_OK;
}

// 销毁共享内存锁
void
ngx_shmtx_destroy(ngx_shmtx_t *mtx)//ngx_shmtx_destroy 函数用于销毁共享内存锁，它接收一个参数，即共享内存锁对象
{
#if (NGX_HAVE_POSIX_SEM)
    // 如果支持 POSIX 信号量，并且 semaphore 标志位已设置，则销毁信号量
    if (mtx->semaphore) {
        if (sem_destroy(&mtx->sem) == -1) {
            ngx_log_error(NGX_LOG_ALERT, ngx_cycle->log, ngx_errno,
                          "sem_destroy() failed");
        }
    }

#endif
}
// 尝试获取共享内存锁
ngx_uint_t
ngx_shmtx_trylock(ngx_shmtx_t *mtx)//ngx_shmtx_trylock 函数用于尝试获取共享内存锁，它接收一个参数，即共享内存锁对象
{
    // 如果锁未被占用（*mtx->lock == 0），则尝试设置锁的值为当前进程的 PID
    // 如果设置成功，则返回 1，否则返回 0
    return (*mtx->lock == 0 && ngx_atomic_cmp_set(mtx->lock, 0, ngx_pid));
}

// 获取共享内存锁
void
ngx_shmtx_lock(ngx_shmtx_t *mtx)//ngx_shmtx_lock 函数用于获取共享内存锁，它接收一个参数，即共享内存锁对象
{
    ngx_uint_t         i, n;

    ngx_log_debug0(NGX_LOG_DEBUG_CORE, ngx_cycle->log, 0, "shmtx lock");//记录一条调试日志

    // 循环尝试获取锁
    for ( ;; ) {

        // 如果锁未被占用，则尝试设置锁的值为当前进程的 PID
        // 如果设置成功，则返回
        if (*mtx->lock == 0 && ngx_atomic_cmp_set(mtx->lock, 0, ngx_pid)) {
            return;
        }

        // 如果 CPU 数量大于 1，则进行自旋等待
        if (ngx_ncpu > 1) {

            for (n = 1; n < mtx->spin; n <<= 1) {

                for (i = 0; i < n; i++) {
                    ngx_cpu_pause();
                }

                // 在自旋等待期间，如果锁未被占用，则尝试设置锁的值为当前进程的 PID
                // 如果设置成功，则返回
                if (*mtx->lock == 0
                    && ngx_atomic_cmp_set(mtx->lock, 0, ngx_pid))
                {
                    return;
                }
            }
        }

#if (NGX_HAVE_POSIX_SEM)

        // 如果支持 POSIX 信号量，并且 semaphore 标志位已设置，则使用信号量进行等待
        if (mtx->semaphore) {
            (void) ngx_atomic_fetch_add(mtx->wait, 1);

            // 在等待信号量期间，如果锁未被占用，则尝试设置锁的值为当前进程的 PID
            // 如果设置成功，则返回
            if (*mtx->lock == 0 && ngx_atomic_cmp_set(mtx->lock, 0, ngx_pid)) {
                (void) ngx_atomic_fetch_add(mtx->wait, -1);
                return;
            }

            ngx_log_debug1(NGX_LOG_DEBUG_CORE, ngx_cycle->log, 0,
                           "shmtx wait %uA", *mtx->wait);

            // 等待信号量
            while (sem_wait(&mtx->sem) == -1) {
                ngx_err_t  err;

                err = ngx_errno;

                // 如果等待信号量失败，并且错误不是因为被中断，则记录错误日志并退出循环
                if (err != NGX_EINTR) {
                    ngx_log_error(NGX_LOG_ALERT, ngx_cycle->log, err,
                                  "sem_wait() failed while waiting on shmtx");
                    break;
                }
            }

            ngx_log_debug0(NGX_LOG_DEBUG_CORE, ngx_cycle->log, 0,
                           "shmtx awoke");

            continue;
        }

#endif

        // 如果不支持 POSIX 信号量，则使用调度器进行等待
        ngx_sched_yield();
    }
}
// 解锁共享内存锁
void
ngx_shmtx_unlock(ngx_shmtx_t *mtx)//ngx_shmtx_unlock 函数用于解锁共享内存锁，它接收一个参数，即共享内存锁对象
{
    // 如果 spin 不等于 -1，记录一条调试日志
    if (mtx->spin != (ngx_uint_t) -1) {
        ngx_log_debug0(NGX_LOG_DEBUG_CORE, ngx_cycle->log, 0, "shmtx unlock");
    }

    // 如果当前进程是锁的持有者，解锁并唤醒等待的进程
    if (ngx_atomic_cmp_set(mtx->lock, ngx_pid, 0)) {
        ngx_shmtx_wakeup(mtx);
    }
}

// 强制解锁共享内存锁
ngx_uint_t
ngx_shmtx_force_unlock(ngx_shmtx_t *mtx, ngx_pid_t pid)//ngx_shmtx_force_unlock 函数用于强制解锁共享内存锁，它接收两个参数，即共享内存锁对象和进程的 PID
{
    // 记录一条调试日志
    ngx_log_debug0(NGX_LOG_DEBUG_CORE, ngx_cycle->log, 0,
                   "shmtx forced unlock");

    // 如果 pid 是锁的持有者，解锁并唤醒等待的进程，然后返回 1
    if (ngx_atomic_cmp_set(mtx->lock, pid, 0)) {
        ngx_shmtx_wakeup(mtx);
        return 1;
    }

    // 如果 pid 不是锁的持有者，返回 0
    return 0;
}
// 唤醒等待共享内存锁的进程
static void
ngx_shmtx_wakeup(ngx_shmtx_t *mtx)//ngx_shmtx_wakeup 函数用于唤醒等待共享内存锁的进程，它接收一个参数，即共享内存锁对象
{
#if (NGX_HAVE_POSIX_SEM)
    ngx_atomic_uint_t  wait;

    // 如果没有使用信号量，直接返回
    if (!mtx->semaphore) {
        return;
    }

    for ( ;; ) {

        // 获取等待的进程数量
        wait = *mtx->wait;

        // 如果没有等待的进程，直接返回
        if ((ngx_atomic_int_t) wait <= 0) {
            return;
        }

        // 尝试减少等待的进程数量
        if (ngx_atomic_cmp_set(mtx->wait, wait, wait - 1)) {
            break;
        }
    }

    // 记录一条调试日志
    ngx_log_debug1(NGX_LOG_DEBUG_CORE, ngx_cycle->log, 0,
                   "shmtx wake %uA", wait);

    // 唤醒一个等待的进程
    if (sem_post(&mtx->sem) == -1) {
        ngx_log_error(NGX_LOG_ALERT, ngx_cycle->log, ngx_errno,
                      "sem_post() failed while wake shmtx");
    }

#endif
}

#else

// 创建共享内存锁
ngx_int_t
ngx_shmtx_create(ngx_shmtx_t *mtx, ngx_shmtx_sh_t *addr, u_char *name)//ngx_shmtx_create 函数用于创建共享内存锁，它接收三个参数，分别是共享内存锁对象、共享内存锁的地址和共享内存锁的名字
{
    // 如果锁已经有名字，并且名字与传入的名字相同，直接返回成功
    if (mtx->name) {

        if (ngx_strcmp(name, mtx->name) == 0) {
            mtx->name = name;
            return NGX_OK;
        }

        // 销毁旧的锁
        ngx_shmtx_destroy(mtx);
    }

    // 打开或创建一个文件，用于实现文件锁
    mtx->fd = ngx_open_file(name, NGX_FILE_RDWR, NGX_FILE_CREATE_OR_OPEN,
                            NGX_FILE_DEFAULT_ACCESS);

    // 如果打开或创建文件失败，记录错误日志并返回错误
    if (mtx->fd == NGX_INVALID_FILE) {
        ngx_log_error(NGX_LOG_EMERG, ngx_cycle->log, ngx_errno,
                      ngx_open_file_n " \"%s\" failed", name);
        return NGX_ERROR;
    }

    // 删除文件
    if (ngx_delete_file(name) == NGX_FILE_ERROR) {
        ngx_log_error(NGX_LOG_ALERT, ngx_cycle->log, ngx_errno,
                      ngx_delete_file_n " \"%s\" failed", name);
    }

    // 设置锁的名字
    mtx->name = name;

    return NGX_OK;
}
// 销毁共享内存锁
void
ngx_shmtx_destroy(ngx_shmtx_t *mtx)//ngx_shmtx_destroy 函数用于销毁共享内存锁，它接收一个参数，即共享内存锁对象
{
    // 关闭文件描述符，如果失败，记录错误日志
    if (ngx_close_file(mtx->fd) == NGX_FILE_ERROR) {
        ngx_log_error(NGX_LOG_ALERT, ngx_cycle->log, ngx_errno,
                      ngx_close_file_n " \"%s\" failed", mtx->name);
    }
}

// 尝试获取共享内存锁
ngx_uint_t
ngx_shmtx_trylock(ngx_shmtx_t *mtx)//ngx_shmtx_trylock 函数用于尝试获取共享内存锁，它接收一个参数，即共享内存锁对象
{
    ngx_err_t  err;

    // 尝试锁定文件描述符
    err = ngx_trylock_fd(mtx->fd);

    // 如果成功，返回 1
    if (err == 0) {
        return 1;
    }

    // 如果文件描述符已经被锁定，返回 0
    if (err == NGX_EAGAIN) {
        return 0;
    }

#if __osf__ /* Tru64 UNIX */

    // 如果没有权限锁定文件描述符，返回 0
    if (err == NGX_EACCES) {
        return 0;
    }

#endif

    // 如果出现其他错误，记录错误日志并返回 0
    ngx_log_abort(err, ngx_trylock_fd_n " %s failed", mtx->name);

    return 0;
}

// 获取共享内存锁
void
ngx_shmtx_lock(ngx_shmtx_t *mtx)//ngx_shmtx_lock 函数用于获取共享内存锁，它接收一个参数，即共享内存锁对象
{
    ngx_err_t  err;

    // 锁定文件描述符，如果失败，记录错误日志
    err = ngx_lock_fd(mtx->fd);

    if (err == 0) {
        return;
    }

    ngx_log_abort(err, ngx_lock_fd_n " %s failed", mtx->name);//记录一条调试日志
}

// 解锁共享内存锁
void
ngx_shmtx_unlock(ngx_shmtx_t *mtx)//ngx_shmtx_unlock 函数用于解锁共享内存锁，它接收一个参数，即共享内存锁对象
{
    ngx_err_t  err;

    // 解锁文件描述符，如果失败，记录错误日志
    err = ngx_unlock_fd(mtx->fd);

    if (err == 0) {
        return;
    }

    ngx_log_abort(err, ngx_unlock_fd_n " %s failed", mtx->name);
}

// 强制解锁共享内存锁
ngx_uint_t
ngx_shmtx_force_unlock(ngx_shmtx_t *mtx, ngx_pid_t pid)//ngx_shmtx_force_unlock 函数用于强制解锁共享内存锁，它接收两个参数，即共享内存锁对象和进程的 PID
{
    // 这个函数在这个版本中没有实现，直接返回 0
    return 0;
}

#endif